This file documents all the changes made to SpriteWorld since version 2.2 was released. Many things were changed that will affect you as a user. If you were previously using a version of SpriteWorld prior to version 2.3.1, it is important that you read through all the changes that have been made since the version you are using was released, and make changes to your source code where necessary. You will only have to do this once, and then will be able to take advantage of the new features in the current version. You should also print out the new versions of the documentation. (Inside SpriteWorld, SpriteWorld - Scrolling, SpriteWorld - Tiling, etc.)
Changes in 2.3.1
Bug fixes:
• Fixed SWSetSpriteDrawProc, which would incorrectly return an error code of type "kWrongDepthErr" when an RLE Sprite with no GWorld was passed to the function. The DrawProc would also not be set, due to the error.
• Fixed a problem where solid-color Sprites (using SWSetSpriteColor and a ColorDrawProc) wouldn't be drawn correctly on 68k Macs.
• Fixed a very minor bug in SpriteTest where choosing a new color for solid-color Sprites didn't affect additional Sprites added after the program started up.
Additions:
• Added SWSetTileMaskSolidMode, which allows you to specify tiles as having solid masks, even after loading them. (You can also specify them as not having a solid mask.)
Changes in 2.3
BlitPixie Changes:
• Totally re-organized BlitPixie, making it easier to use, faster, and also usable without SpriteWorld. However, lots of DrawProc names have changed. The following DrawProcs replace those that used to be in BlitPixie8Bit.c and BlitPixieDoubleRect.c:
BlitPixieRectDrawProc
BlitPixieMaskDrawProc
BlitPixiePartialMaskDrawProc
BlitPixieDoubleRectDrawProc
These routines work in 8-bit, 16-bit, and 32-bit on both PPC and 68k, and automatically do interlacing depending on your settings. (See the new SWSetFrameInterlacingMode.)
All of the new DrawProcs work in any depth of 8-bits or greater.
The names of the BlitPixieAllBit DrawProcs have not been changed. However, these DrawProcs can no longer be used when compiling for PPC. The PPC version has been removed, since it only handled depths of 8-bits and above, which the new BlitPixie routines now handle. So BlitPixieAllBit is really only useful on 68k Macs when you need blitters for depths lower than 8-bits. If your code compiles for both 68k and PPC, make sure to sandwich any references to the AllBit blitters between "#if SW_68k" and "#endif", since the blitters are undefined on PPC.
Other non-DrawProc functions that have also been expanded to handle depths of 8-bits and higher:
BlitPixie8BitGetPixel -> SWGetPixel
BlitPixie8BitSetPixel -> SWSetPixel
SWAnimate8BitStarField -> SWAnimateStarField
BlitPixie8BitFlipSprite -> SWFlipSprite
SWPixelCollision -> SWPixelCollision
SWFlipSprite now works in any depth, although it is slow in depths below 8-bits. It also now re-creates any kind of mask (pixel, region, or fat mask), and will even re-compile a compiled Sprite.
SWGetPixel and SWSetPixel also work in any depth, including those below 8 bits. SWSetPixel no longer checks to make sure the pixel is inside its Frame before writing it. Additionally, both functions now accept x and y parameters for the pixel location, rather than a Point. And finally, there is a new macro you can use to set/get pixels quickly, that is faster than SWGetPixel and SWSetPixel. See the documentation for those functions for more information.
SWPixelCollision's name didn't change, but it does now handle depths of 16-bits and 32-bits.
• Many file names were changed in the BlitPixie re-organization. BlitPixie8Bit.c and BlitPixieDoubleRect.c no longer exist, and there are a bunch of new files that should be added to your project in the SpriteWorld Files -> BlitPixie -> Sources folder. The easiest way to do this is to simply drag and drop that folder onto your project's window, and rename the segment as BlitPixie. (Make sure to remove BlitPixie8Bit.c, BlitPixieDoubleRect.c, and BlitPixieiAllBit.c from your project first.) You will also need to add BlitPixieInterface.c to your project, which is contained in the SpriteWorld Files -> Sources folder. (Add it to your SpriteWorld segment.)
Other Changes:
• Attention Multi-Screen Scrolling.c users! A new function has been added that you must call in your main animation loop: SWFinishProcessingMultiScreenSW. See the Multi-Screen Scrolling docs for more info.
• Attention SWAnimateStarField users! A new "isOn" boolean variable has been added to the StarArray that must be set to true when your initialize your stars, or else they won't be drawn! See the documentation for SWAnimateStarField in Inside SpriteWorld for more information about this variable.
• Added a Boolean createGWorld parameter to the end of SWCreateFrame. This parameter is used internally by SpriteWorld to avoid creating GWorlds for RLE Sprites. If you call SWCreateFrame directly, you should pass true as this parameter.
• Added a srcWindowP parameter to the beginning of SWCreateWindowFrame. This specifies the window you wish to create the Frame in. Also, it is no longer necessary to set the port to that window before calling SWCreateWindowFrame, since the function now does that for you.
• Removed SWFastCloneSprite, since it wasn't really any faster than SWCloneSprite. If you used SWFastCloneSprite, simply change your code to call SWCloneSprite instead.
• Made BlitPixieRotated much faster on 68k Macs, and slightly faster on PPC Macs as well.
• BlitPixieScaled and BlitPixieRotated now handle 32 bits, in addition to the 16-bit and 8-bit depths they previously handled.
• Modified BlitPixie8BitLitRectDrawProc and BlitPixie16BitLitRectDrawProc so they work in a scrolling world. However, they only work if you scroll in multiples of the lighting size. (The lighting size is set in the call to SWInitializeLightingSquares.)
• Modified SWSaveTileMap so it doesn't erase the old resource's name if you replace an existing TileMap.
• SWDrawTile now saves and restores the current port. Previously, this function was throwing off people who were using GetMouse(), and expected the port to be the same as it was before they called SWDrawTile.
• A new Sprite's MoveProc will now be called only after the Sprite has been drawn in its original position. Previously, this may or may not have happened, depending on when the Sprite was added to the animation. This is important, since if, for example, you have a spaceship that shoots a bullet that comes out of the spaceship's gun, the bullet should be drawn in its starting location before it's moved. Now this will happen consistently, regardless of when the Sprite is added to the animation.
• Removed the destSpriteWorldP parameter from SWUpdateFrameMasks, since it is no longer needed.
• Added new code that speeds up the creation of self-masking Sprites when in 8-bit or above, especially self-masking Sprites that use a transparent color other than white. And while I haven't done any tests, it may be slightly faster to create a self-masking Sprite than it is to create a Sprite that has a mask loaded from a resource.
These speedups also affect SWUpdateFrameMasks, which is now quite a bit faster than it was before when used on Sprites containing a pixel mask in 8 bits or above. In addition, when you use a masking blitter that works in 16-bits or 32-bits, the DrawProc you specify is now the one that is actually used. Previously, due to the way masks were handled, whenever you used an masking blitter in 16-bits or above, a slower partial mask blitter was used instead.
• Added a Boolean parameter to SWLoadTilesFromCicnResource and SWLoadTilesFromPictResource that tells those functions whether the tile(s) you are loading have normal masks or partial masks. (This parameter is ignored if there is no pixelMask.) This change was necessary due to some other speedups that were made. See SWLoadTilesFromPictResource for more information about this new parameter.
• SWSetPortToWindow will now give an assertion error if the SpriteWorld is not locked when the function is called.
• Apple's free MPW compiler is now supported! See the SpriteWorld-MPW ReadMe in the Documentation folder for more information.
• CodeWarrior Pro 5 project files have been added. The old CodeWarrior 10 project files are also still included. The CW 10 files end with ".µ", while the Pro 5 project files end with ".mcp".
• All Think C projects have been removed, since it would be more work that it's worth to try to update them. (Especially since no one in their right mind should be using Think C any more!)
Additions:
• Added SWStats.c, a collection of routines that allow you to easily add Sprites that display numbers, such as the score or number of lives left, in either the main animation window or a separate stats area. See "Add-On Docs" folder for more information.
• Added SWParticles.c, for adding particle animations to your scrolling or non-scrolling games. See "Add-On Docs" folder for more information.
• Added SWSortSpriteLayer, which sorts a SpriteLayer so that Sprites lower on the screen are drawn on top of Sprites higher on the screen.
• Add SWSetFrameInterlacingMode, which allows you to control whether anything drawn in a specified frame will skip every other line or not, and if so, whether to skip even or odd lines.
• Added SWSetFrameCollisionInset, which shrinks the area used when checking for collisions. Useful for Frames that contain "extra" space that shouldn't be taken into account when doing collision detection.
• Added SWUnwrapWorkAreaToBackground, which allows you to temporarily "unwrap" the work area so you can copy it to the screen using your own custom special screen-wipe function.
• Added SWGetPreviousSprite - a companion to SWGetNextSprite.
• Added SWGetSpriteHorizLoc and SWGetSpriteVertLoc. Use these instead of accessing the Sprite's destFrameRect directly to get its position, as these routines take the Sprite's hotSpot into account.
• Added SWSetSpriteColor, which allows you to set the color your Sprite is drawn with when you are using one of the color DrawProcs.
• Added SWSetBackgroundColor, which allows you to set the color the background of your SpriteWorld is drawn with when you are using a clear DrawProc as your offscreenDrawProc. Useful for space games, or other games where the entire background is a solid color. (Using a clearDrawProc is faster than the other offscreenDrawProcs.)
• Added several new DrawProcs, useful for drawing either the background or individual Sprites as solid colors:
SWStdWorldClearProc
BlitPixieClearDrawProc
SWStdSpriteColorDrawProc
BlitPixieMaskColorDrawProc
BlitPixieRLEColorDrawProc
See SWSetSpriteColor and SWSetBackgroundColor documentation for more information.
• Added a resType parameter to SWLoadTileMap and SWSaveTileMap. This allows you to save and load TileMaps that use a different resType than the default 'TMAP'. Simply pass 'TMAP' as the first parameter to these functions if you want them to behave as they did previously.
• Added SetChannelRate to SWSounds.c. Also made the rate parameter of PlaySound2 active. Passing a rate other than 1.0 (or k22khz, which is defined to 1.0), will make the sound higher or lower in pitch.
• Added HideControlStrip and RestoreControlStrip to SWGameUtils.c. Thanks to Gareth White for contributing these well-written routines! It is recommended that you use these routines instead of the KeepMenuBarHidden function, also in SWGameUtils.c. Also added ResourceExists to SWGameUtils.c; useful for checking to see if a resource exists without loading it.
• Added SWSetCleanUpFunction, which allows you to install a callback that is called whenever an assertion failure or a fatal error occurrs. This is very useful for doing important things such as fading the screen back in if it was faded out when the failure occurred, as well as anything else you need to do before quitting. (Like restoring the Control Strip.)
Bug Fixes:
• SpriteWorld no longer has any problems with multiple monitors! You can now drag windows between monitors, and the animation will continue properly even if you use blitters, provided that you call SWWindowMoved whenever moving the window. (The monitors must also be the same depth if you drag windows between them and use a blitter as your screenDrawProc.)
• Changed some code in BlitPixieDoubleRect.c to avoid a bug in CodeWarrior Pro 5's assembler where the "bne" operator would be translated to "bgel", instead of "bnl" or "bge". So the scrolling demos will no longer crash when compiled under CodeWarrior Pro 5.
• Fixed a bug in SWCollideSpriteLayer where collisions between a single srcSpriteP and multiple dstSpriteP's would be detected, even when the srcSpriteP was removed after the first collision.
• Fixed a problem in SWSwapSprite where the function would create an endless loop in the linked list of Sprites if the two Sprites being swapped were not adjacent, and one was the head or tail Sprite. Also fixed the same problem in SWSwapSpriteLayers.
• Fixed a nasty bug in SWSaveTileMap where if a TileMap was resized, saved, and loaded again all without quitting the program, you may have had all sorts of strange problems. Worse yet, this bug only showed up some of the time, and only on some systems. It's actually a problem with the Resource Manager and the unique method I use to save TileMaps, but I was able to find a way around the bug.
• Fixed a bug in SWProcessSpriteWorld where if you set your max fps rate to 0, and called SWProcessSpriteWorld in a tight loop by itself to process many frames of the animation at once without animating them, the Sprites' MoveProcs and FrameProcs wouldn't get called unless at least one 1000th of a second had passed since the previous call to SWProcessSpriteWorld.
• Fixed a bug in the scrolling engine where idle Sprites could get erased by invisible Sprites that had scrolled off the screen and were turned visible again.
• Fixed a bug in Brian's Translucency blitter that causes it to sometimes draw white artifacts on 68k in 256 colors.
• Multi-Screen Scrolling.c now avoids a bug in CodeWarrior's 68k optimizer that could cause tile artifacts or even crashes.
• If an assertion error occurred, SpriteWorld didn't turn off the CleanUpSpriteWorld's VBL Syncing as it should have. This has been fixed.
